What is a symbolic debugger?

A debugger is a tool that helps you track down and eliminate errors (or "bugs") in program code. Typically you use a debugger to pause the program at a point which you wish to investigate, then analyse the contents of variables at that point. You can also trace through the flow of the program to see exactly which code is executed and the effect it has on the data.

The Basic4GL debugger

The Basic4GL debugger is integrated directly into Basic4GL itself. It supports the following features:

Stepping
Breakpoints
Watches (including mouse-over hints)
Stack display

Activating the debugger

When Basic4GL starts the debugger displays and buttons are hidden (although most of them can still be used if you know the keyboard shortcuts).
To switch between debug mode and normal mode, click the "Basic4GL" menu on the main menu bar then "Debug Mode", OR press the corresponding button on the toolbar OR press Ctrl+D.
Basic4GL will now display the "watch" and "stack" windows along the bottom, and add the "stepping" buttons to the toolbar.

Stopped, running and paused

To correctly understand and use the Basic4GL debugger you will need to become familiar with these three modes:
(it's actually simpler than it sounds!)

Stopped
This means that the program has stopped completely.
The editor is enabled.
The debugging tools show the state of the program when it finished/was stopped.
When the program is next run, it will be run from the start.
Running
This means the Basic4GL program is running.
You cannot edit the program code.
If Basic4GL is in fullscreen mode, then the screen is displaying the program's output.
Paused
This is the mode that the stepping and breakpoint tools will put Basic4GL into. The program has been paused midway through running, and the debugging tools show the state of the program at that time.
Unlike "stopped" mode, the program code cannot be edited, and when the program is run again, it will continue on from the point at which it was paused.

So if you wish to edit the program, you will need to ensure it is "stopped", not just "paused" (press the "Stop" button on the toolbar).

To debug a section of code, you will need to "pause" Basic4GL at that point (either using a breakpoint, or by stepping to it, or pressing the "pause" button).

Go/Stop vs Play/Pause

The Go/Stop button (displays a "Go" or "Stop" sign depending on the mode) is used to run the program from the start, or stop it completely so that it can be edited.

The Play/Pause debugging button (displays a play arrow or a pause sign) is used to pause the program or resume it from the position it was paused.

Stepping

Basic4GL supports these standard functions for stepping through code:

Step over
Step into (gosub)
Step out of (gosub)

They behave like any other debugger, that is:

Step over

"Step over" runs the current line of code and pauses on the next line. If the current line contains a "gosub" call, it will not step into it. Instead it will run the entire gosub routine and return.

For example, for the following program:

dim a, b: a = 10: b = 20        ' 1
gosub Two                       ' 2
printr a                        ' 3
end                             ' 4
Two:                            ' 5
    printr b                    ' 6
    return                      ' 7

Clicking "Step over" once will pause the program on line 2. Clicking it again will pause the program on line 3, despite the fact that lines 6 and 7 were also executed by the "gosub" call (and 20 was printed on the screen).

Step into

"Step into" behaves exactly like step over, except when the current line contains a "gosub" call.
In this case the program is paused on the first line of the "gosub" routine.

For example, for the previous program, clicking "Step Into" once will pause the program on line 2. Clicking it again will pause the program on line 6. (Then line 7, then line 3.)

Step out of

"Step out of" is only available if the program has been paused inside a gosub call. "Step out of" will run the rest of the "gosub" routine and pause the program on the instruction immediately after the actual "gosub" call.

So on the above program, clicking "Step into" twice to get to line 6 will make the "Step out of" function available. Clicking "Step out of" will then pause the program on line 3, i.e. the instruction immediately after the "gosub" on line 2.

Breakpoints

A "breakpoint" is used to pause a program at a particular line of code. You place the breakpoint on the line (or lines) where you wish to pause the program, and then run it. The program will continue running until it reaches the line (or lines) of code. When it does so, it will pause at the start of the line, before executing any of the code on it.

To place a breakpoint, click on the gray area on the left side of the editor, next to the line where you wish to pause the program. Basic4GL indicates breakpoints with a small stop sign. To remove the breakpoint, simply click it again.

You can add a breakpoint at any time, even if the program is running (except in fullscreen mode obviously). The breakpoint becomes active from the moment you click it in.
Breakpoints will only work on lines that correspond to executable code. If you place a breakpoint on a line with no corresponding code, it will be dithered out to indicate that it is inactive.

Watches

Watches display the value of a variable. Watches are only active when the program is stopped or paused, and are displayed in the wide window immediately under the editor (when debug mode is on).

To add a watch, double click the blank line at the top of the watches list and type in the variable or expression you wish to watch. Alternatively you can right click a variable in the editor and choose "Add watch".
Basic4GL will now display the variable/expression, along with it's value, so you can track changes to it (e.g. as you step through lines of code).

Side effects

You can watch any valid Basic4GL expression, including arithmetic expressions and functions.
Beware of functions that have side effects. For example, placing a watch on "ReadInt (file)" (read an integer from file with handle "file") will advance the current position in the file each time the watch is evaluated, and most likely cause the code that you are debugging to fail.
(And don't place a watch on "Input$ ()", as it will crash Basic4GL! This will be fixed...)

Mouse-over hints

You can also quickly see the value of a variable by moving the mouse over it in the editor. To quickly see the result of an expression, highlight it first, then move the mouse over it.
Mouse-over hints will not evaluate functions (otherwise we could get unexpected side effects from accidently moving the mouse over a function). You must use a watch for this instead.

Stack display

The "stack display" lists all the active "gosub" calls. This is somewhat simpler than most debuggers, as Basic4GL "gosubs" don't have parameters or other information passed in.

The stack display is the small window at the bottom right (when debug mode is active). It is only active in "paused" mode.

The top most entry is always "IP", which corresponds to the current instruction pointer. Double clicking this will move the cursor to the current line being executed.
The remaining lines are "gosub" calls. Double click each to move to display the line of source code containing the call.

Keyboard shortcuts

The debugging keyboard shortcuts are based on both the Borland and Microsoft standards.

Function	Shortcut (Borland)	Shortcut (Microsoft)
Step over	F8	F10
Step into	F7	F11
Step out of	Shift + F8	Shift + F10
Run/Pause	F9	F5
Add watch	Ctrl + F5

Be aware that F9 in Microsoft debugging environments means "set breakpoint", which is F5 in Borland debugging environments! (Basic4GL doesn't have a set breakpoint keyboard shortcut.)

Keyboard shortcuts in the program output window

The following keys can be pressed in the output window, while the program is running. (This is especially useful in full-screen mode, as the editor keys are unavailable.)

Esc stops the program completely.

Pause pauses the program.